Scripting
So, you want to learn how to script? This should be the very first place to look. Be sure to read everything carefully, making sure that you understand what is being read. If you have any questions or comments feel free to ask them either on the discussion page or on the Forum. Introduction The ROBLOX scripting language is Lua 5.1, a concise and efficient scripting language used in games and embedded systems. Documentation on the language can be found at here. Scripting requires the Script object which can control a number of things. For list of Lua objects that can be used, see the Class Reference. This article is documentation for people slightly familiar with the language. If you have no idea what you're doing, you may want to look at these: *Absolute beginner's guide to scripting *Flowcharts *Reusing code Intro to Scripting: Make a Dance Floor is a tutorial for beginners that shows how scripts can be used to control the color of parts. Also, when scripting it is also important to look at the Object Browser. Keep it open when you're making scripts in Edit mode. It can show where and why you've made a mistake. Fundamentals These are the basics. It is very important to understand these. Defining Scripts Script objects can be placed under the Workspace or under parts, models, values, etc. Scripts can also be written and executed in the Command toolbar. To execute a script from the command bar: #Edit a place in GOODBLOX Studio. #Select View-->Toolbars-->Command from the menu bar. #:The Command toolbar will appear at the bottom of the screen. #Select View-->Output from the menu bar. #:The Output panel will appear just above the Command toolbar. #In the Command toolbar's textbox type the following: #: print("Hello World") #Press the 'Enter' key. #:The text "Hello World" appears in the Output window Script Execution Script objects only run under certain conditions: * Scripts entered in the Command toolbar execute when you press Enter. This only applies if you're in either edit mode or Solo mode. * Scripts will run, as said before, if under the Workspace or general containers. * Scripts inside a Tool run when the Tool is activated. Also, if you want a script to NOT run when the game is started, make sure that under the Properties for a script, the Bool 'Disabled', is set to true. A script will also not run if under the Lighting, Sound Service, or any Service besides the Workspace. If the script's property is under the DataModel, then it will also not run. Environments and Libraries Each Script has its own copy of the global Environment. This "sandboxes" each script. For instance another script cannot overwrite the global data defined in another script. ROBLOX loads the following Lua standard libraries: Basic Functions, Coroutine Manipulation, String Manipulation, Table Manipulation, Mathematical Functions. For security purposes some functions have been removed to deny access to system resources. A list of these functions can be found in the Function Dump page of the wiki. In addition, some Roblox Lua Objects have been removed for the very same reason. Math One important feature that nearly all programming languages use is math. Here's what you need to know: *You can use the Output to view your solutions. You can use other types of output too, like messages and hints. *Roblox can perform complex probelms for you. *This can make things extremely simple. Here's a sample of basic math. Open up GOODBLOX Studio, goto File> New, insert a Script into the Workspace, make sure that the Output is open. For more information, and usage, read the following articles: *Basic math *Variables *Conditional statements *Random numbers *How To Increase and Decrease Vector3 Values Data Model The DataModel is what you would define as 'game' in your scripts. Here are Lua 'types' that can be used in a script Basic Types GOODBLOX scripts use the basic Lua types nil, boolean, number, string, function, userdata, thread, and table. In addition, there are the following additional basic types: Vector3 Vector3 represents a 3D vector. All properties are Read-Only. CFrame CFrame, know as character frame, but more specifically coordinate frame. Color3 Color3, sets color likely in Hex format (e.g. 1, 255, 98). BrickColor Example: local b = BrickColor.Yellow() print(b.r) prints: 0.96078437566757 BrickColor Codes image:RobloxColors.PNG + Use SirGelatina's Color Reference Connection Represents a connection to an Event ; Globals In addition to loading several Standard Libraries ROBLOX defines the following global variables: * game is the DataModel object that is the root of the tree for a Place. * workspace is the Workspace object that is a child of the DataModel. * script is the Script object that defines the script. (not applicable for the Command toolbar) * print() echoes each argument to the Output panel. * time() returns returns the current game time in seconds. (NOTE: THis function is scheduled for an upcoming release) * wait(t) yields the current thread after "t" seconds have elapsed. If t is not specified, then it yields for a very short period of time. The function returns 2 values: The elapsed time and the current game time. * delay(t,f) executes function "f" after "t" seconds have elapse. The function "f" is called with 2 arguments: The elapsed time and the current game time. Roblox Objects See Main List: RBX.lua Objects Each object in the Explorer is accessible with scripting. ROBLOX Objects have Properties, Functions and Events. You can browse the member definitions by clicking Class Explorer under the Help menu. Properties Object properties are accessed with the “dot” notation: script.Name = "Hello" print(script.Name) Some properties are Read-Only. Attempting to assign to a read-only property will throw an error. Functions Member functions are called using the "colon" operator: copy = script:clone() print(copy.Name) Functions in Lua are first-class objects. Therefore you can reference a member function as follows: f = script.clone copy = f(script) print(copy.Name) Note: If you are used to other scripting languages you will need remember to use : instead of . when invoking a member function. script.clone() will not behave as you might expect. Events Events are fired by Objects. Scripts define code to be executed when an event is fired. Events can optionally send one or more arguments when fired. There are two ways to handle an Event: # When a script calls wait(), the currently executing thread yields until the Event is fired. The return values from wait() are the Event arguments. # A script calls connect() passing in a function that the Event will call each time the Event is fired. connect() immediately returns a Connection object that can be used to disconnect the listener function. Here is some sample code: -- Get the Script's Parent object part = script.Parent -- Define a handler for the "Touched" Event function onTouched(otherPart) print(otherPart.Name .. " touched me!") end -- Listen for each time that "part" is touched connection = part.Touched:connect(onTouched) -- Put this thread to sleep until a property changes propName = part.Changed:wait() print("Property changed: " .. propName) -- Stop listening to the Touched event connection:disconnect() This code listens for two events: The Part being touched and also for a Changed event. Since we connected to the Touched event, the function onTouched() will be called each time Part is touched. However, once the Changed Event fires and the wait() call returns, we won't listen for another Changed event. At that point we also disconnect from the Touched event. You are not strictly required to disconnect every connection you make. If the Object owning the Event is collected, then the listening script will no longer get events. Similarly, if the Script Object that owns the listener is removed, then the connection is automatically broken, and any waiting threads can be collected. Object Types There are many different object types in Roblox, and in addition to adding them through the Roblox Studio, you can also define a new object in a script with the line Instance.new("className"), with className being the object's type. Following is a listing of many of the various object types. Common Mistakes The slightest misspelling, or even incorrect capitalization will result in your script failing to work. REMEMBER: Look at the Output to check for errors. If this doesn't help, back-track and make sure everything is perfect. If you think there is a problem, or you need help in general, report the problem to the Bugs article, and request help on the Forum. For more help, see the 'See Also' section at the bottom of the page. See Also In the beginning:... *Your first script *Basic Scripting *Explaining Scripts *Loops *How To Increase and Decrease Vector3 Values *In-Depth Scripting Guide Scripting Tutorials and Articles: *Commands *Intro to Scripting: Make a Healing Potion *In-Depth Scripting Guide *Intro to Scripting: Make an Invisibility Tool *Teleportation *How to make lava *How to Make Weapon Giving Teleporters *How Do I Make Morphs? *How to Create a Black Hole *How to Make Conveyor Belts *How to Make a Plane *How to make circles *How to make a spiral staircase *How to make a double helix General Information: *Random numbers *Commands *Conditional statements *Variables *Flowcharts *Generic for *Bool *String *Flowcharts *Linked lists *Functions *Tables Support: *Request Lua Feature *Bugs Category:Scripting Tutorials Category:Reference Pages